home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / program / 168 / readme.doc < prev    next >
Text File  |  1988-04-17  |  11KB  |  229 lines
  1. Distribution Disk - Shareware Atari ST C compiler - version 2.0
  2.          copyright 1988 - Mark A. Johnson
  3.                           5315 Holmes Place
  4.                           Boulder, CO 80303
  5.                           GEnie login: MAJOHNSON
  6.  
  7. This disk contains a shareware C compiler for your use and enjoyment,
  8. pass it on to anyone freely as long as it includes this note.
  9.  
  10. I bought my 520ST in April 1986.  Almost all the software I have is either 
  11. public domain or shareware.  I have supported the shareware idea in the past,
  12. but I'd like to see it happen for myself.  If you like what you find here,
  13. please send a donation along with your name and address.  I send out a
  14. newsletter to discuss bugs, enhancements, and hints now and then.  I hope 
  15. you enjoy this software.  It is not for sale by anyone, and I reserve all 
  16. rights to its  ownership.  Feel free to pass it on to other ST owners, 
  17. but please pass on the whole disk, including this "readme" file.  
  18.  
  19. This is the distribution disk for version 2.0 of the compiler.
  20. It contains the basic compiler tools, libraries, source for the libraries, 
  21. source for a number of useful tools, and (hardly any) documentation.
  22.  
  23. The compiler can handle the full language specified in Kernigan & Ritchie's
  24. "The C Programming Language." To save space, the distribution is contained 
  25. in three ARC files:
  26.  
  27.     mjc.arc    - the compiler development environment
  28.     lib.arc    - source code for the libraries
  29.     srcdoc.arc    - source code for a few useful tools and documentation
  30.  
  31. I've also included ARC.TTP to allow you to unpack the disk.  
  32. Here's a description of the files contained in the all the archives:
  33.  
  34. Programs
  35.     cc.ttp    - translates C code to intermediate code
  36.     as.ttp    - translates intermediate code to machine code
  37.     ue.ttp    - public domain microEmacs editor 
  38.     mk.ttp    - simple UN*X style "make" program
  39.     eternal2.prg- a PD ramdisk, survives resets
  40.     ramdisk.dat - data file for ramdisk
  41.     autodisk.prg- Moshe Braner's autoboot floppy copy to ramdisk on boot
  42.  
  43. Libraries and Header Files
  44.     prg.s    - startup intermediate code for .PRG programs
  45.     ttp.s    - startup intermediate code for .TTP programs
  46.     lib.a    - library used to create .TTP programs
  47.     gem.a    - library used to create .PRG programs
  48.     lib.c    - source for most of lib.a
  49.     math.c    - source for the long and floating point math routines
  50.     str.c    - source for the string routines
  51.     fmtio.c    - source for printf, scanf, and all its friends
  52.     gem.c       - source code for gem.a
  53.     stdio.h    - header for the standard i/o routines
  54.     setjmp.h    - header for setjmp/longjmp routines
  55.     gem.h    - header for GEM AES routines
  56.     osbind.h    - header for "standard" GEMTOS bindings
  57.  
  58. Source code
  59.     ss.c    - a simple spreadsheet program
  60.     hd.c        - a hex dump program
  61.     mk.c    - the make program used in the development environment
  62.     lorder.c    - a library checker (makes sure the order is ok)
  63.     bug.c       - tells you what happened in a crash
  64.     
  65. Documentation
  66.     as.doc    - documentation on the intermediate code
  67.     readme.doc    - this file
  68.     eternal2.doc- describes ramdisks in general and eternal2 in particular
  69.     autodisk.doc- describes what autodisk.prg does and how to use it
  70.  
  71. I have a 520ST with one single-sided floppy, so this disk is really a
  72. collection of many disks I use.  Let's get started by making an autobooting
  73. development environment disk.  Copy MJC.ARC and ARC.TTP to a fresh floppy
  74. and extract all the files out of MJC.ARC (see ARC.DOC).  Then do the 
  75. following (in order):
  76.  
  77.     create an AUTO folder
  78.     copy ETERNAL2.PRG into AUTO
  79.         copy AUTODISK.PRG into AUTO
  80.         copy RAMDISK.DAT into AUTO
  81.         the following files should be in the root directory
  82.         UE.TTP
  83.         CC.TTP
  84.         AS.TTP
  85.         MK.TTP
  86.         TTP.S
  87.         LIB.A
  88.         DESKTOP.INFO
  89.  
  90. Now, whenever you boot the system with this disk, it will prompt you for the
  91. date (it's important to tell it the truth, MK.TTP uses file timestamps
  92. to tell whether or not to build something), copy all the files to the
  93. ramdisk, and then puts you back on the desktop.
  94.  
  95. The compiler (CC.TTP) is preprocessor, parser, and code generator all rolled
  96. into a single program.  Please refer to the "C Programming Language" by K&R.
  97. The compiler has the following features beyond K&R:
  98.  
  99.     - symbol names can be any length
  100.     - built-in 6800 trap generator "trap(NUM, arg1, arg2, ...)"
  101.     - structure assignments
  102.     - register variables
  103.     - "assembler" escapes
  104.     - enum's
  105.  
  106. The floating point is homebrew and new to version 2.0, I am sure it is slow
  107. and buggy.  Be forewarned.  If anyone can improve the floating point code
  108. (see MATH.C in the library source), please let me know so I can 
  109. incorporate it into future releases.
  110.  
  111. The output of the compiler is ascii text and each line maps into a 
  112. single instruction.  This intermediate code is as terse as I can make it (to
  113. save disk space) but is still readable (by me at least).  (I have plans to 
  114. improve this to make things easier for an optimizer).  The output of the 
  115. compiler is always placed in a file called "yc.out" in the current directory.
  116. Any error messages are displayed on the screen.  If "-o filename" is present
  117. on the command line, output will be placed in the specified file instead of
  118. YC.OUT.  The other options to CC.TTP include "-I directory" which gives the
  119. compiler optional directories to search for include files, and "-D name" or
  120. "-D name=value" which lets you #define things on the command line.
  121.  
  122. The assembler (AS.TTP) reads the intermediate code in a single pass and 
  123. keeps everything in memory before generating the file "ya.out" in the 
  124. current directory.  The size limit of the program to be compiled is basically
  125. the size of the available memory.  The "ya.out" file should be renamed to 
  126. one of the standard extensions (.TTP, .PRG, .TOS) before executing it.  
  127. The command line of the assembler should always list a startup file 
  128. first (see ttp.s or prg.s) then the intermediate files of the program, 
  129. then "-L" followed by any libraries.  Any errors encountered by the 
  130. assembler terminates assembly.  A "-m" argument to the assembler will 
  131. include the symbol table (standard Atari format) in the output file.  
  132. A "-o filename" argument will place the output in the specified file instead
  133. of in YA.OUT.  Finally, for those times when the command line is too short
  134. (it's only 128 characters on the ST) a "-f filename" allows AS.TTP to read 
  135. in its list of files to be assembled from a file.
  136.  
  137. A library is simply intermediate code, but is handled differently by the 
  138. assembler than regular intermediate code.  Intermediate code (the 
  139. files before "-L") are read and processed directly; all symbols and
  140. code are accepted without question.  A library is read without processing 
  141. until a symbol is found that is needed but not defined.  From that point 
  142. on, the library is read and processed until the next symbol is encountered.
  143. At the next symbol, the "needed but not defined" test is applied again 
  144. and processing or scanning continues as necessary.
  145.  
  146. The libraries include TOS, VDI, and AES routines taken from the Abacus books.
  147. See lib.doc for some info on the library routines.  I have also included basic
  148. <stdio.h> routines.  I have included the source for LIB.A and GEM.A.  A lot 
  149. of library routines you would expect to see are missing, and for that I 
  150. apologize.  My next major project for the compiler is to port Dale 
  151. Schumaker's DLIB package to MJC.
  152.  
  153. Creating .TTP programs is straightforward and better tested than .PRG (GEM) 
  154. program creation.  In a .TTP process, the main function is called with 
  155. the standard arguments:
  156.  
  157.     main(argc, argv) int argc; char *argv[];
  158.  
  159. Redirection of input and output using >outfile, >>appendfile, or <infile 
  160. on the command line is handled by a startup routine linked into the 
  161. compiled program.  Reads and writes to the screen are built to map '\n' 
  162. to/from "\n\r".
  163.  
  164. Support for GEM programs (.PRG) is not completely debugged.  The GEM.A 
  165. library includes all the VDI and AES functions in the Abacus books,
  166. but has not been extensively tested.  The VDI routines work and 
  167. the window routines, form_alert, and evnt_multi of AES are working.  
  168. My stumbling block right now is adequate documentation 
  169. that would enable me to build a (working) Resource Construction Set.  
  170. I'm (still) working on it...  (Actually, I'm ready to give up on GEM and
  171. roll my own window manager that has forms, menus, and windows, and doesn't
  172. need resource files to work).
  173.  
  174. Let me give you an example of how I use these tools.  I boot with the
  175. disk we made above that sets up my environment with all the tools in
  176. the ramdisk.
  177.  
  178. I then insert a working disk (I only have a single floppy!).
  179. I use microEmacs (UE.TTP) to create or edit C programs.  The MK.TTP program
  180. has built-in rules that enable it to build .TTP or .PRG programs out of
  181. .C source files without any makefile needed.  MK.TTP also will search for
  182. a drive that has a makefile on it, which for me is normally A:.  When I
  183. start up MK.TTP out of the ramdisk, it usually goes over to A: and starts
  184. doing it's thing.  For example, I click on MK.TTP and in the form enter
  185.  
  186.     grep.ttp
  187.  
  188. This will compile the program grep.c and create an executable called grep.ttp.
  189.  
  190. If the C program is contained in a number of files, I normally create a
  191. makefile MK.TTP can use.  Intermediate files are created from the C source
  192. (again a built-in rule in MK.TTP) and finally the object is linked together
  193. by an entry in the makefile.  For example, say I have a spreadsheet program
  194. composed of four files: main.c, io.c, calc.c, and display.c.  The following
  195. makefile would do the trick:
  196.  
  197. # makefile for a (mythical) spreadsheet program
  198.  
  199. OBJ = main.s io.s calc.s display.s
  200.  
  201. ss.ttp: $(OBJ)
  202.   d:as.ttp d:ttp.s $(OBJ) -L d:lib.a
  203.     
  204. io.c main.c display.c: stdio.h
  205.  
  206.  
  207. With the above, I can build the spreadsheet after editing by simply double 
  208. clicking and letting it go.  When you don't tell MK.TTP what to build, it
  209. will build the first object it finds, which in the above example is SS.TTP.
  210.  
  211. Only those files that need to be compiled will be compiled.  When everything
  212. is compiled then the objects will be linked together to form the executable.
  213. The source for MK.TTP is included SRC.ARC, so take a look in there for more 
  214. information on how it works.  It has lots of functions built-in which you
  215. may find useful.  
  216.  
  217. If you insist on doing things by hand, then double click CC.TTP and give it
  218. an argument like "file.c".  This will compile FILE.C into intermediate code, 
  219. which is found in YC.OUT in the current directory.  You can then double
  220. click AS.TTP and give it "d:ttp.s yc.out -L d:lib.a" to assemble and link 
  221. the startup file TTP.S, the compiler output YC.OUT and the library LIB.A.  
  222. For GEM programs, you can replace TTP.S with PRG.S and add GEM.A after the -L.
  223.  
  224. To build libraries or tools, use the compiler.  There are makefiles included
  225. with the source code for them.  Write me if you have problems with any of this!
  226.  
  227.  
  228.  
  229.